<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>scanf - C++ Reference</title>
<style type="text/css">.hierarchy DIV {width:100px; height:24px; text-align:center; padding-top:8px; border:black 1px solid} </style>
<link rel="shortcut icon" type="image/x-icon" href="/favicon.ico">
<link rel="stylesheet" type="text/css" href="/main29d.css">
<script src="/main29d.js" type="text/javascript"></script>
<script type="text/javascript">
new LoginBox('CH_boxLogin',1);</script>
</head>
<body>
<div id="CH_header">
	<a href="/"><img src="/img/cpp-logo.png" alt="cplusplus.com" width="198" height="75"></a>
	<div id="CH_bar">
		<b><a href="/">C++</a> : <a href="/reference/">Reference</a> : <a href="/reference/clibrary/">C Library</a> : <a href="/reference/clibrary/cstdio/">cstdio (stdio.h)</a> : scanf</b>
	</div>
	
	<div id="CH_searchbox">
		<form id="search" action="/search.do" method="get">
		Search: <input name="q" size="13" class="txt"> <input type="submit" value="Search" class="btn">
		</form>
	</div>
	<div id="CH_boxLogin"><div class="loginmessage">&nbsp;<img src="/img/waitblue.gif"></div>
	</div>
</div>
<div id="CH_container">
<table id="CH_containertbl"><tr>
<td id="CH_nav">
<table class="box">
<thead>
<tr><th><a href="/">cplusplus.com</a></th></tr>
</thead>
<tbody>
<tr><td class="folder"><a href="/info/">Information</a></td></tr>
<tr><td class="folder"><a href="/doc/">Documentation</a></td></tr>
<tr><td class="folder selected"><a href="/reference/">Reference</a></td></tr>
<tr><td class="folder"><a href="/articles/">Articles</a></td></tr>
<tr><td class="folder"><a href="/src/">Sources</a></td></tr>
<tr><td class="folder"><a href="/forum/">Forum</a></td></tr>
</tbody>
</table>
<table class="box">
<thead><tr><th><a href="/reference/">Reference</a></th></tr></thead>
<tbody><tr><td class="selected folder"><a href="/reference/clibrary/">C Library</a></td></tr>
<tr><td class="folder"><a href="/reference/iostream/">IOstream Library</a></td></tr>
<tr><td class="folder"><a href="/reference/string/">Strings library</a></td></tr>
<tr><td class="folder"><a href="/reference/stl/">STL Containers</a></td></tr>
<tr><td class="folder"><a href="/reference/algorithm/">STL Algorithms</a></td></tr>
<tr><td class="folder"><a href="/reference/std/">Miscellaneous</a></td></tr>
</tbody>
</table>
<table class="box">
<thead><tr><th><a href="/reference/clibrary/">C Library</a></th></tr></thead>
<tbody><tr><td class="folder"><a href="/reference/clibrary/cassert/">cassert (assert.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cctype/">cctype (ctype.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cerrno/">cerrno (errno.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cfloat/">cfloat (float.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/ciso646/">ciso646 (iso646.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/climits/">climits (limits.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/clocale/">clocale (locale.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cmath/">cmath (math.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/csetjmp/">csetjmp (setjmp.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/csignal/">csignal (signal.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cstdarg/">cstdarg (stdarg.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cstddef/">cstddef (stddef.h)</a></td></tr>
<tr><td class="selected folder"><a href="/reference/clibrary/cstdio/">cstdio (stdio.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cstdlib/">cstdlib (stdlib.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/cstring/">cstring (string.h)</a></td></tr>
<tr><td class="folder"><a href="/reference/clibrary/ctime/">ctime (time.h)</a></td></tr>
</tbody>
</table>
<table class="box">
<thead><tr><th><a href="/reference/clibrary/cstdio/">cstdio (stdio.h)</a></th></tr></thead>
<tbody><tr><td class="folder">functions:</td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/clearerr/">clearerr</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fclose/">fclose</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/feof/">feof</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/ferror/">ferror</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fflush/">fflush</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fgetc/">fgetc</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fgetpos/">fgetpos</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fgets/">fgets</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fopen/">fopen</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fprintf/">fprintf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fputc/">fputc</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fputs/">fputs</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fread/">fread</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/freopen/">freopen</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fscanf/">fscanf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fseek/">fseek</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fsetpos/">fsetpos</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/ftell/">ftell</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fwrite/">fwrite</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/getc/">getc</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/getchar/">getchar</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/gets/">gets</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/perror/">perror</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/printf/">printf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/putc/">putc</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/putchar/">putchar</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/puts/">puts</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/remove/">remove</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/rename/">rename</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/rewind/">rewind</a></td></tr>
<tr><td class="selected indent"><a href="/reference/clibrary/cstdio/scanf/">scanf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/setbuf/">setbuf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/setvbuf/">setvbuf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/sprintf/">sprintf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/sscanf/">sscanf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/tmpfile/">tmpfile</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/tmpnam/">tmpnam</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/ungetc/">ungetc</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/vfprintf/">vfprintf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/vprintf/">vprintf</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/vsprintf/">vsprintf</a></td></tr>
<tr><td class="folder">macro constants:</td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/EOF/">EOF</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/FILENAME_MAX/">FILENAME_MAX</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/NULL/">NULL</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/TMP_MAX/">TMP_MAX</a></td></tr>
<tr><td class="folder">objects:</td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/stderr/">stderr</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/stdin/">stdin</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/stdout/">stdout</a></td></tr>
<tr><td class="folder">types:</td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/FILE/">FILE</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/fpos_t/">fpos_t</a></td></tr>
<tr><td class="indent"><a href="/reference/clibrary/cstdio/size_t/">size_t</a></td></tr>
</tbody>
</table>
<div id="CH_subnav"></div>
<br>
<script type="text/javascript"><!--
google_ad_client = "pub-7688470879129516";
/* single square */
google_ad_slot = "7465536459";
google_ad_width = 125;
google_ad_height = 125;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script>
	</td>
	<td id="CH_main">
<script type="text/javascript"><!--
google_ad_client = "pub-7688470879129516";
google_ad_slot = "7973859818";
google_ad_width = 728;
google_ad_height = 90;
//-->
</script>
<script type="text/javascript"
src="http://pagead2.googlesyndication.com/pagead/show_ads.js">
</script><br><div class="C_doctop">
<h1>scanf</h1>
<div class="right">function</div>
</div>
<div class="docsubtop">
<div class="right"><code>&lt;cstdio&gt;</code></div>
<div class="prototype"><pre>int  scanf ( const char * format, ... );</pre></div>
</div>
<p><strong>Read formatted data from stdin</strong></p>
Reads data from <tt>stdin</tt> and stores them according to the parameter <i>format</i> into the locations pointed by the additional arguments. The additional arguments should point to already allocated objects of the type specified by their corresponding format tag within the <i>format</i> string.<br>
<br>
<h3>Parameters</h3>
<dl>
<dt>format</dt>
<dd>C string that contains one or more of the following items:<br>
<blockquote><ul>
<li><b>Whitespace character:</b> the function will read and ignore any whitespace characters (this includes blank spaces and the newline and tab characters) which are encountered before the next non-whitespace character. This includes any quantity of whitespace characters, or none.</li>
<li><b>Non-whitespace character, except percentage signs (%):</b> Any character that is not either a whitespace character (blank, newline or tab) or part of a format specifier (which begin with a <tt>%</tt> character) causes the function to read the next character from <tt>stdin</tt>, compare it to this non-whitespace character and if it matches, it is discarded and the function continues with the next character of <i>format</i>. If the character does not match, the function fails, returning and leaving subsequent characters of <tt>stdin</tt> unread.</li>
<li><b>Format specifiers:</b> A sequence formed by an initial percentage sign (<tt>%</tt>) indicates a format specifier, which is used to specify the type and format of the data to be retrieved from <tt>stdin</tt> and stored in the locations pointed by the additional arguments. A format specifier follows this prototype:<br>
<br>
%[*][width][modifiers]type<br>
<br>
where:<br>
<br>
<table class="boxed"><tr><td><i>*</i></td><td>An optional starting asterisk indicates that the data is to be retrieved from <tt>stdin</tt> but ignored, i.e. it is not stored in the corresponding argument.</td></tr>
<tr><td><i>width</i></td><td>Specifies the maximum number of characters to be read in the current reading operation</td></tr>
<tr><td><i>modifiers</i></td><td>Specifies a size different from <tt>int</tt> (in the case of <tt>d</tt>, <tt>i</tt> and <tt>n</tt>), <tt>unsigned int</tt> (in the case of <tt>o</tt>, <tt>u</tt> and <tt>x</tt>) or <tt>float</tt> (in the case of <tt>e</tt>, <tt>f</tt> and <tt>g</tt>) for the data pointed by the corresponding additional argument:<br>
<b>h :</b> <tt>short int</tt> (for <tt>d</tt>, <tt>i</tt> and <tt>n</tt>), or <tt>unsigned short int</tt> (for <tt>o</tt>, <tt>u</tt> and <tt>x</tt>)<br>
<b>l :</b> <tt>long int</tt> (for <tt>d</tt>, <tt>i</tt> and <tt>n</tt>), or <tt>unsigned long int</tt> (for <tt>o</tt>, <tt>u</tt> and <tt>x</tt>), or <tt>double</tt> (for <tt>e</tt>, <tt>f</tt> and <tt>g</tt>)<br>
<b>L :</b> <tt>long double</tt> (for <tt>e</tt>, <tt>f</tt> and <tt>g</tt>)<br>
</td></tr>
<tr><td><i>type</i></td><td>A character specifying the type of data to be read and how it is expected to be read. See next table.</td></tr></table>
<br>
<b>scanf type specifiers:</b>
<table class="boxed"><tr><th>type</th><th>Qualifying Input</th><th>Type of argument</th></tr>
<tr><td><tt>c</tt></td><td><b>Single character:</b> Reads the next character. If a <i>width</i> different from 1 is specified, the function reads <i>width</i> characters and stores them in the successive locations of the array passed as argument. No null character is appended at the end.</td><td><tt>char *</tt></td></tr>
<tr><td><tt>d</tt></td><td><b>Decimal integer:</b> Number optionally preceded with a <tt>+</tt> or <tt>-</tt> sign.</td><td><tt>int *</tt></td></tr>
<tr><td><tt>e</tt>,<tt>E</tt>,<tt>f</tt>,<tt>g</tt>,<tt>G</tt></td><td><b>Floating point:</b> Decimal number containing a decimal point, optionally preceded by a <tt>+</tt> or <tt>-</tt> sign and optionally folowed by the <tt>e</tt> or <tt>E</tt> character and a decimal number. Two examples of valid entries are -732.103 and 7.12e4</td><td><tt>float *</tt></td></tr>
<tr><td><tt>o</tt></td><td><b>Octal integer</b>.</td><td><tt>int *</tt></td></tr>
<tr><td><tt>s</tt></td><td><b>String of characters</b>. This will read subsequent characters until a whitespace is found (whitespace characters are considered to be blank, newline and tab).</td><td><tt>char *</tt></td></tr>
<tr><td><tt>u</tt></td><td>Unsigned decimal integer.</td><td><tt>unsigned int *</tt></td></tr>
<tr><td><tt>x</tt>,<tt>X</tt></td><td>Hexadecimal integer.</td><td><tt>int *</tt></td></tr></table>
</li></ul></blockquote>
</dd>
<dt>additional arguments</dt>
<dd>The function expects a sequence of references as additional arguments, each one pointing to an object of the type specified by their corresponding <tt>%</tt>-tag within the <i>format</i> string, in the same order.<br>
For each format specifier in the <i>format</i> string that retrieves data, an additional argument should be specified.<br>
These arguments are expected to be references (pointers): if you want to store the result of a <tt>fscanf</tt> operation on a regular variable you should precede its identifier with the <i>reference operator</i>, i.e. an ampersand sign (<tt>&</tt>), like in: <br>
<blockquote><tt>
int n;<br>
scanf ("%d",&n);<br>
</tt></blockquote></dd></dl>
<br>
<h3>Return Value</h3>
On success, the function returns the number of items succesfully read. This count can match the expected number of readings or fewer, even zero, if a matching failure happens.<br>
In the case of an input failure before any data could be successfully read, <a href="/EOF">EOF</a> is returned.<br>
<br>
<h3>Example</h3>
<div class="auto"><table class="snippet"><tr><td class="rownum"><tt>1<br>2<br>3<br>4<br>5<br>6<br>7<br>8<br>9<br>10<br>11<br>12<br>13<br>14<br>15<br>16<br>17<br>18<br>19<br></tt></td>
<td class="source"><pre><code><cite>/* scanf example */</cite>
<dfn>#include &lt;stdio.h&gt;</dfn>

<var>int</var> main ()
{
  <var>char</var> str [80];
  <var>int</var> i;

  printf (<kbd>"Enter your family name: "</kbd>);
  scanf (<kbd>"%s"</kbd>,str);  
  printf (<kbd>"Enter your age: "</kbd>);
  scanf (<kbd>"%d"</kbd>,&amp;i);
  printf (<kbd>"Mr. %s , %d years old.\n"</kbd>,str,i);
  printf (<kbd>"Enter a hexadecimal number: "</kbd>);
  scanf (<kbd>"%x"</kbd>,&amp;i);
  printf (<kbd>"You have entered %#x (%d).\n"</kbd>,i,i);
  
  <var>return</var> 0;
}</code></pre></td></tr></table></div>
<br>
<br>
This example demonstrates some of the types that can be read with <tt>scanf</tt>:<br>
<tt>Enter your family name: Soulie<br>
Enter your age: 29<br>
Mr. Soulie , 29 years old.<br>
Enter a hexadecimal number: ff<br>
You have entered 0xff (255).</tt>
<br>
<h3>See also</h3>
<table class="C_docLink"><tr><td class="tit"><a href= "/reference/clibrary/cstdio/fscanf/"><b>fscanf</b></a></td><td class="des"> Read formatted data from stream <span class="typ">(function)</span></td></tr></table><table class="C_docLink"><tr><td class="tit"><a href= "/reference/clibrary/cstdio/printf/"><b>printf</b></a></td><td class="des"> Print formatted data to stdout <span class="typ">(function)</span></td></tr></table><table class="C_docLink"><tr><td class="tit"><a href= "/reference/clibrary/cstdio/gets/"><b>gets</b></a></td><td class="des"> Get string from stdin <span class="typ">(function)</span></td></tr></table><table class="C_docLink"><tr><td class="tit"><a href= "/reference/clibrary/cstdio/fopen/"><b>fopen</b></a></td><td class="des"> Open file <span class="typ">(function)</span></td></tr></table>
<div id="CH_bb"></div><script type="text/javascript">new doc_Page('CH_bb','/reference/item.cgi',88,0,0,32768);</script>
<p>


</td></tr></table>
</div>
<div id="CH_footer">
	<a href="/">Home page</a> | <a href="/privacy.do">Privacy policy</a><br>&copy; cplusplus.com, 2000-2011 - All rights reserved - <i>v2.9</i><br><a href="/contact.do?referrer=http://www.cplusplus.com/reference/clibrary/cstdio/scanf/">Spotted an error? contact us</a>
</div>

<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
onPrint.print();
var gso = new Session ('ssn29','rel29',14400,86400,1301124398);
_uacct = "UA-521783-1";
urchinTracker();
</script>
</body>
</html>